From 88906ececc078645479529a0c1a7e990826007f6 Mon Sep 17 00:00:00 2001 From: parkrrrr Date: Fri, 19 May 2006 11:50:15 +0000 Subject: [PATCH] dd 'styles' appendix --- xmldoc/chapters/_chapters.xml | 2 + xmldoc/chapters/allchapters.xml | 1 + xmldoc/chapters/styles.xml | 972 ++++++++++++++++++++++++++++++++ 3 files changed, 975 insertions(+) create mode 100644 xmldoc/chapters/styles.xml diff --git a/xmldoc/chapters/_chapters.xml b/xmldoc/chapters/_chapters.xml index 6ce0611e4..34349a230 100644 --- a/xmldoc/chapters/_chapters.xml +++ b/xmldoc/chapters/_chapters.xml @@ -5,3 +5,5 @@ + + diff --git a/xmldoc/chapters/allchapters.xml b/xmldoc/chapters/allchapters.xml index bffbe70e8..92db51bcf 100644 --- a/xmldoc/chapters/allchapters.xml +++ b/xmldoc/chapters/allchapters.xml @@ -4,3 +4,4 @@ &chap_formats; &chap_filters; &app_datums; +&app_styles; diff --git a/xmldoc/chapters/styles.xml b/xmldoc/chapters/styles.xml new file mode 100644 index 000000000..5374a10f5 --- /dev/null +++ b/xmldoc/chapters/styles.xml @@ -0,0 +1,972 @@ + +GPSBabel XCSV Style Files + +The format of an XCSV style file is quite simple and designed to be easily +implemented by non-programmers to handle "one-off" babel-ization of various +XCSV (whatever separated values) text files. The format and usage of the +various style directives are described below. + + +The first and foremost important step is understanding how the config +file is laid out itself. The format is: + +DIRECTIVE<whitespace>VALUE + +Where <whitespace> is a space, tab, spaces, tabs, etc... There should +be nothing before the directive. (i.e. not " DIRECTIVE VALUE") + +
+Internal Constants + +A few internal constants are defined in the XCSV parser to make the style +file simpler. They may or may not be used and are optional in most cases. +Note that only certain style file directives map these constants. + + +STYLE CONSTANT MAPS TO CHAR(s) +--------------------------------------- +COMMA , +COMMASPACE ,<space> +SINGLEQUOTE ' +DOUBLEQUOTE " +COLON : +SEMICOLON ; +NEWLINE \n +CR \r +CRNEWLINE \r\n +TAB \t +SPACE <space> +HASH # +PIPE | +WHITESPACE *** SEE WHITESPACE NOTES BELOW *** + +
+WHITESPACE + +The WHITESPACE constant has special properties. When reading data, +WHITESPACE refers to sequential runs of SPACES and/or TABS. When +writing data, WHITESPACE is always a single SPACE. + + +For example, the following line: + + +SOME_NAME 30.1208 -91.1365 SOME OTHER NAME + + +Parses into the following data fields: + + +SOME_NAME,30.1208,-91.1365,SOME,OTHER,NAME + +
+ +
+COMMENTS + +Anything after a hash (#) on a line is not parsed. For example: + + +#THIS ENTIRE LINE IS A COMMENT. +#FIELD LAT_DECIMAL, "", "%f" THIS ENTIRE LINE IS A COMMENT +FIELD LAT_DECIMAL, "", "%f" # ONLY THIS SENTENCE IS A COMMENT. + +
+
+ +
+Global Properties of the File + +There are a few available directives to describe general traits of the +file being described and not specific data within the file itself. + +
+DESCRIPTION + +This is the description of the file format being described. This text +appears in the help screens and in menus used by the various GUI wrappers. + +
+
+EXTENSION + +This directive gives the filename extension generally associated with +this file. + +
+
+ENCODING + +Describes the character set used by this format. The value given +must be one listed by 'gpsbabel -l'. example: + + + ENCODING UTF-8 # Use UTF-8 for input and output. + +
+
+ +
+GPSBabel Behavior Directives + +There are a few available directives to control some of the internal +processing functions of GPSbabel. + +
+SHORTLEN + + This sets the maximum allowed shortname length when using the internal + shortname synthesizer. + + + example: + + + SHORTLEN 16 # shortnames will be at most 16 characters long. + +
+ +
+SHORTWHITE + + This tells the shortname synthesizer whether or not to allow whitespace + in the synthesized shortnames. Allowed values are zero and one. + + + example: + + + SHORTWHITE 0 # Do not allow whitespace in shortname. + SHORTWHITE 1 # Allow whitespace in shortname. + +
+
+ +
+Defining the Layout of the File + +The first few directives define the layout the physical file itself: + + +
+FIELD_DELIMITER + + The field delimiter defines the character(s) that separate the fields in + the rows of data inside the XCSV file. Common field delimiters are commas + and tabs. (referred to as "comma separated values" and "tab separated + values") + + + examples: + + + FIELD_DELIMITER COMMA + FIELD_DELIMITER ~ + + + The directive FIELD_DELIMITER is parsed for STYLE CONSTANTS as defined in + the table above. + +
+ +
+RECORD_DELIMITER + + The record delimiter defines that character(s) that separate ROWS of + data (FIELDS) in the XCSV file. The most common record delimiters + are NEWLINE and CR (carriage return). + + + examples: + + + RECORD_DELIMITER NEWLINE + RECORD_DELIMITER | + + + The directive RECORD_DELIMITER is parsed for STYLE CONSTANTS as defined + in the table above. + +
+ +
+BADCHARS + + Bad characters are things that should *never* be written into the XCSV + file as data on output. GPSBabel automatically includes any non-blank + FIELD_DELIMITER and RECORD_DELIMITER characters as BADCHARS by default. + + + examples: + + + BADCHARS COMMA + BADCHARS ~| + + + The directive BADCHARS is parsed for STYLE CONSTANTS as defined in the + table above. + +
+ +
+PROLOGUE + + A prologue is basically constant data that is written to the output + file BEFORE any waypoints are processed. PROLOGUE can be defined + multiple times in the style file, once for each "line" before the data + begins. This is commonly used in XCSV files as a "header" row. + + + examples: + + + PROLOGUE OziExplorer Waypoint File Version 1.1 + PROLOGUE WGS 84 + PROLOGUE Symbol,Name,Latitude,Longitude + +
+ +
+EPILOGUE + + An Epilogue is the same as a prologue, except this data is written at + the END of the file. See the examples for PROLOGUE above. + +
+
+ +
+Defining Fields Within the File + +A field defines data. There are two different classifications of FIELDS, +IFIELD (file input) and OFIELD (file output). In the absence of any OFIELDS, +IFIELDS are use as both input and output. The existence of OFIELDS is +primarily to allow more flexible mapping of GPSBabel data to output data +(say, for instance, to map the internal GPSBabel "description" variable to +two or more fields on output). For all practical purposes, IFIELDS and +OFIELDS are defined the same way in the style file. The following options +are defined: + + + + + "no_delim_before" is supported on OFIELD tags to specify that this + field should be written without a field delimiter before it. It's + useful for limited field concatenation. + + + + + + "absolute" is supported on OFIELD tags for lat and lon to indicate + that only absolute values (never negative) are to be printed. + + + + + +There are several different types of fields that may be defined. Each field +consists of three pieces of information: the FIELD TYPE, a DEFAULT VALUE, and +a PRINTF CONVERSION (for output). In many cases, not all pieces are used, +but all 3 pieces are required. Additionally, an fourth field is supported +that modifies the behaviour of the field being described. + + +FIELDS should be defined in the style file in the logical order that they +appear in the data, from left to right. This is the order in which they are +parsed from input and written to output. + + +The fields used by the XCSV parser are as follows: + + +
+IGNORE + + IGNORE fields are, guess what, ignored on input. Internally, IGNORE + fields are treated as CHARACTER data, and as such, require a printf + conversion for a character array. + + +examples: + + + IFIELD IGNORE,"","%14.14s" # (writes a 14 character blank field) + IFIELD IGNORE,"","%s" # (writes a blank field on output) + +
+ +
+CONSTANT + + CONSTANT fields are, of course, constant. They are ignored on input, + however they write CONSTANT data on output. As such, they require a + DEFAULT VALUE and a printf conversion for a character array. + + +examples: + + + IFIELD CONSTANT,"FFFFFF","%s" # (writes "FFFFFF" in the field) + IFIELD CONSTANT,"01/01/70","%s" # (a constant date field) + +
+ +
+INDEX + + An INDEX field is used ONLY on output. The INDEX constant defines a field + that, at output, contains the sequence number of the waypoint being + written, starting at 0. An index is managed internally as an INTEGER + and requires an INTEGER printf conversion. An INDEX has one special + property. The DEFAULT VALUE of the index is added to the index + on each iteration (to allow indexes starting at 1, 100, etc..). + + +examples: + + + IFIELD INDEX,"0","%04d" # (Starts counting at zero) + IFIELD INDEX,"","%04d" # (Starts counting at zero) + IFIELD INDEX,"1","%04d" # (Starts counting at one) + +
+ +
+SHORTNAME + + A SHORTNAME is generally the waypoint name of the data being processed. + SHORTNAME maps directly to the GPSBabel variable ->shortname. A SHORTNAME + is CHARACTER data and requires a character array printf conversion. + + +example: + + + IFIELD SHORTNAME,"","%s" # (write shortname in the output file) + +
+ +
+DESCRIPTION + + A DESCRIPTION is generally a long description of the waypoint. A + DESCRIPTION maps to the GPSBabel variable ->description and is otherwise + handled exactly like a SHORTNAME. + + +examples: + + + IFIELD DESCRIPTION,"","%s" # (write description in the output file) + +
+ +
+NOTES + + NOTES are generally everything else about a waypoints. NOTES map to the + GPSBabel variable ->notes and is otherwise handled exactly like a + SHORTNAME. + +
+ +
+URL + + URL is a URL for the waypoint. URL maps to the GPSBabel variable + ->url and is otherwise handled exactly like a SHORTNAME. + + +example: + + + IFIELD URL,"","%s" # (writes the URL in the output file) + +
+ +
+URL_LINK_TEXT + + URL_LINK_TEXT is a textual description of where a URL points. + URL_LINK_TEXT maps to the GPSBabel variable ->url_link_text and + is otherwise handled exactly like a SHORTNAME. + + +example: + + + IFIELD URL_LINK_TEXT,"","%s" # (writes link text in the output file) + +
+ +
+ICON_DESCR + + ICON_DESCR is a textual description of an icon type for a waypoint. + ICON_DESCR maps to the GPSBabel variable ->icon_desc and is otherwise + handled exactly like a SHORTNAME. + + +example: + + + IFIELD ICON_DESCR,"","%s" # (writes link text in the output file) + +
+ +
+LAT_DECIMAL + + LAT_DECIMAL defines LATITUDE in DECIMAL format. Note that this is a PURE + signed decimal format (i.e. -91.0000). This data is handled internally as + a DOUBLE PRECISION FLOAT and requires a FLOATING POINT printf conversion. + + +example: + + + IFIELD LAT_DECIMAL,"","%f" + +
+ + +
+LON_DECIMAL + + See LAT_DECIMAL, except LON_DECIMAL defines LONGITUDE. + +
+ +
+LAT_INT32DEG + + LAT_INT32DEG defines LATITUDE in what I call INT32DEGREES. This value is + a signed LONG INTEGER and requires a LONG INTEGER printf conversion. + (This format is only used by some DeLorme products.) + + +example: + + + IFIELD LAT_INT32DEG,"","%ld" + +
+ +
+LON_INT32DEG + + See LON_INT32DEG except LON_INT32DEG defines LONGITUDE. + +
+ +
+LAT_DECIMALDIR / LAT_DIRDECIMAL + + LAT_DECIMALDIR and LAT_DIRDECIMAL define LATITUDE in DECIMAL format + with the added bonus of a 'N/S' or 'E/W' direction character. This data + is handled internally as a DOUBLE PRECISION FLOAT and a single + CHARACTER and requires a FLOATING POINT as well as a CHARACTER printf + conversion. The only difference between the two is whether the directional + character appears before (LAT_DIRDECIMAL) or after (LAT_DECIMALDIR) the + decimal number. + + +examples: + + + IFIELD LAT_DECIMALDIR,"","%f %c" # (writes 31.333 N) + IFIELD LAT_DIRDECIMAL,"","%c %f" # (writes N 31.333) + +
+ +
+LON_DECIMALDIR / LON_DIRDECIMAL + + Same as LAT_DECIMALDIR / LAT_DIRDECIMAL except LON_ defines LONGITUDE. + +
+ +
+LAT_DIR / LON_DIR + + LAT_DIR returns the single character 'N' or 'S' depending on the + hemisphere of the latitude. LON_DIR returns 'E' or 'W' depending on + the hemisphere of the longitude. + +
+ +
+LAT_HUMAN_READABLE + + LAT_HUMAN_READABLE defines LATITUDE in a human-readable format. This + format is probably the most expressive format. It is similar to + LAT_DECIMALDIR in that it requires multiple printf conversions, but it + is far more flexible as to the contents of those conversions. On read, + the printf conversions are ignored and GPSBabel attempts to determine the + latitude and longitude based on what is in the file. + + +examples: + + + IFIELD LAT_HUMAN_READABLE,"","%c %d %f" # (writes N 31 40.000) + IFIELD LAT_HUMAN_READABLE,"","%d deg %f min %c" + # (writes "31 deg 40.000 min N") + # Note that this string will confuse the reading routine due + # to the letter "n" in "min" and the letter "e" in "deg." + IFIELD LAT_HUMAN_READABLE,"","%d %d %f%c" # (writes 31 40 00.000N) + +
+ +
+LON_HUMAN_READABLE + + See LAT_HUMAN_READABLE except LON_HUMAN_READABLE defines LONGITUDE. + +
+ +
+LATLON_HUMAN_READABLE + + LATLON_HUMAN_READABLE is like LAT_HUMAN_READABLE and LON_HUMAN_READABLE + except that it reads and writes both latitude and longitude as a single + field. On write, the same format specifier is used for both coordinates. + On read, GPSBabel does exactly the same thing it does for + LAT_HUMAN_READABLE or LON_HUMAN_READABLE. + + +example: + + + IFIELD LATLON_HUMAN_READABLE,"","%c %d %f" + # (writes "N 31 40.126 W 85 09.62" as a single field) + +
+ +
+LAT_NMEA + + Defines the latitude in the format used by the NMEA standard which is + degrees multiplied by 100 plus decimal minutes. + + +example: + + + IFIELD LAT_NMEA, "%f", "%08.3f" # (writes 3558.322) + +
+ +
+LON_NMEA + + Defines the longitude in the format used by the NMEA standard which is + degrees multiplied by 100 plus decimal minutes. + + +example: + + + IFIELD LON_NMEA, "%f", "%010.3f" # (writes -08708.082) + +
+ +
+ALT_FEET + + ALT_FEET is the position's ALTITUDE in FEET. This value is treated as + a SIGNED DOUBLE PRECISION FLOAT and requires a FLOATING POINT printf + conversion. + + +example: + + + IFIELD ALT_FEET,"","%.0f" + +
+ +
+ALT_METERS + + ALT_METERS is identical to ALT_FEET with the exception that the altitude + is in METERS. + +
+ +
+HEART_RATE + + Heart rate, measured in beats per minute. Only valid for units with + heart rate monitor features (i.e. Garmin Forerunner 301). + + +example: + + + IFIELD HEART_RATE,"","%d" + +
+ +
+EXCEL_TIME + + EXCEL_TIME is the waypoint's creation time, if any. This is actually + the decimal days since 1/1/1900 and is handled internally as a DOUBLE + PRECISION FLOAT and requires a FLOATING POINT printf conversion. + + +example: + + + IFIELD EXCEL_TIME,"","%11.5f" + +
+ +
+TIMET_TIME + + TIMET_TIME is the waypoint's creation time, if any. This is actually + the integer seconds since 1/1/1970 (let's not start the holy war) and + is handled internally as a LONG INTEGER and requires a LONG INTEGER + printf conversion. + + +example: + + + IFIELD TIMET_TIME,"","%ld" + +
+ +
+YYYYMMDD_TIME + + YYYYMMDD_TIME is the waypoint's creation time, if any. It's a single + decimal field containing four digits of year, two digits of month, + and two digits of date. Internally it is a LONG INTEGER and thus + requires a LONG INTEGER printf conversion. + + +example: + + + IFIELD YYYYMMDD_TIME,"","%ld" + +
+ +
+GMT_TIME + + GMT_TIME is the waypoint's creation time, in UTC time zone. It uses the + strptime conversion format tags. + + +example: + + + IFIELD GMT_TIME,"","%m/%d/%Y %I:%M:%D %p" + + + Search the web for 'strptime man page' for details strptime, but one + such page can be found at +http://www.die.net/doc/linux/man/man3/strptime.3.html + +
+ +
+LOCAL_TIME + + LOCAL_TIME is the waypoint's creation time, in the local + time zone. It uses strptime conversion format tags. See GMT_TIME for a + reference. + + +example: + + + IFIELD LOCAL_TIME,"","%y-%m-%d" + +
+ +
+HMSG_TIME + + HMSG_TIME parses up to three time parts and am/pm string to add + this value to the previously parsed *_TIME field that contains + only a date. On output, will print the time in UTC. + + +example: + + + IFIELD HMSG_TIME,"","%d:%d:%d %s" + +
+ +
+HMSL_TIME + + HMSG_TIME parses up to three time parts and am/pm string to add + this value to the previously parsed *_TIME field that contains + only a date. On output, will print the time in local time. + + +example: + + + IFIELD HMSL_TIME,"","%dh%dm" + +
+ +
+ISO_TIME + + ISO_TIME is the waypoint's creation time, in ISO 8601 format, + which include time zone information. + It is expected to be in the format yyyy-mm-ddThh:mm:sszzzzz + where zzzzzz is the local time offset or the character Z + for UTC time. + On output, UTC 'Z' time zone will always be used. + + +example: + + + IFIELD ISO_TIME,"","%s" + +
+ +
+GEOCACHE_DIFF + + GEOCACHE_DIFF is valid only for geocaches and represents a DOUBLE + PRECISION FLOAT. This is the geocache "difficulty" rating as defined by + Groundspeak. A "three and a half star" cache would therefore be "3.5" + + +example: + + + IFIELD GEOCACHE_DIFF,"","%3.1f" + +
+ +
+GEOCACHE_TERR + + GEOCACHE_TERR is valid only for geocaches and represents a DOUBLE + PRECISION FLOAT. This is the geocache "terrain" rating as defined + by Groundspeak. A "three and a half star" cache would therefore be "3.5" + + +example: + + + IFIELD GEOCACHE_TERR,"","%3.1f" + +
+ +
+GEOCACHE_CONTAINER + + GEOCACHE_CONTAINER is valid only for geocaches and is heavily influenced + by the Groundspeak container types. Examples would include "Micro" + and "Virtual". + + +example: + + + GEOCACHE_CONTAINER,"","%s" + +
+ +
+GEOCACHE_TYPE + + GEOCACHE_TYPE is valid only for geocaches and is heavily influenced + by the Groundspeak cache types. Examples would include "Event cache" + and "Multi-Cache". + + +example: + + + GEOCACHE_TYPE,"","%s" + +
+ +
+GEOCACHE_PLACER + + GEOCACHE_PLACER is a string containing the name of the placer of a + geocache. + + +example: + + + GEOCACHE_PLACER,"","%s" + +
+ +
+GEOCACHE_LAST_FOUND + + A long integer in format YYYYMMDD containing the last time this geocache + was found. + + +example: + + + GEOCACHE_LAST_FOUND,"","%ld" + +
+ +
+GEOCACHE_HINT + + The hint for this geocache. No additional transformation (such as rot13) + will be performed on this string. + + +example: + + + GEOCACHE_HINT,"","%s" + +
+ +
+PATH_DISTANCE_MILES + + PATH_DISTANCE_MILES outputs the total length of the route or track from + the start point to the current point, in miles. This and the altitude + could be used to create an elevation profile. PATH_DISTANCE_MILES is + a DOUBLE PRECISION FLOAT. + + + PATH_DISTANCE_MILES is not valid as an input field. + + + PATH_DISTANCE_MILES is only meaningful if the data comes from a track + or a route; waypoint data will generate essentially meaningless output. + + +example: + + + PATH_DISTANCE_MILES,"","%f" + +
+ +
+PATH_DISTANCE_KM + + PATH_DISTANCE_KM is like PATH_DISTANCE_MILES except it outputs the + length in kilometers. + +
+ +
+PATH_SPEED + + Speed in meters per second. Gpsbabel does NOT calculate this data by + default; it is read from the input file if present. (If not present, + it may be calculated with the track + filter.) + + +example: + + + PATH_SPEED,"","%f" + +
+ +
+PATH_COURSE + + Course in degerees. Gpsbabel does not calculate this data by default; + it is read from the input file if present. (If not present, it may be + calculated with the track filter.) + + +example: + + + PATH_COURSE,"","%f" + +
+ +
+GPS_HDOP / GPS_VDOP / GPS_PDOP + + GPS horizontal / vertical / positional dilution of precision + parameters. Needs float conversion. + + +example: + + + GPS_HDOP,"","%f" + +
+ +
+GPS_SAT + + Number of satellites used for determination of the position. Needs + integer conversion. + + +example: + + + GPS_SAT,"","%d" + +
+ +
+GPS_FIX + + Type of fix (see GPX spec or track +filter). Needs string conversion. + + +example: + + + GPS_FIX,"","%s" + +
+
+ +
+Examples + +For examples on using the XCSV module, please see the +*.style files in the +style/ subdirectory of GPSBabel. + +
+ +
+Miscellaneous Notes +
+Default Values + +Default values are supported for any output fields that contain pure + character data output such as URL and NOTES. Default values are only + written on output and are not used to supplement missing input. When + using default values your mileage will vary greatly depending on the + input formats used to populate waypoint data. + +
+
+ + -- 2.30.2